fix(mode): fail loud on a half-configured client instead of silently reading the on-box store - #60

Finding: 0.2.92's local default was DELIBERATE HARDENING, not an accidental regression

Read the diff before choosing a fix. The behaviour change came in with PR #43
fix/f22a263f-explicit-mode-and-egress-guard (merge 4226c25, 2026-07-28),
which sits squarely inside the published 0.2.91 -> 0.2.92 window:

Nothing about it is accidental. It added src/knowledge-mode.ts (191 lines,
entirely about this one decision), tests/knowledge-mode.test.ts (215 lines) with
tests named "REGRESSION: url + key with no mode var stays LOCAL", a new
knowledge mode command, and README changes. The module header states the rule
and the incident it came from: an ambient HASNA_KNOWLEDGE_API_URL +
HASNA_KNOWLEDGE_API_KEY exported in a login shell and inherited by every tmux
pane silently routed a test suite's writes at the live store, surfacing as a
flood of unrelated failures. It also closed a second inference layer in
@hasna/contracts via pinnedTransportEnv.

So restoring 0.2.91's presence-based routing would reintroduce a known,
documented data-integrity incident. This PR does not do that.

What this PR changes

It keeps the strictness and removes the silence it left behind.

Measured on this branch before the fix, in a sandbox HOME with the pointer set
and no mode var:

$ knowledge list --json
{ "ok": true, "total": 0, "items": [], "store_exists": false }   # exit 0

A successful-looking empty page on a machine explicitly pointed at a store
holding 869 entries (station01 measured 98 local vs 869 hosted). knowledge mode
reported the ignored pointer correctly the whole time — but nothing runs
knowledge mode before trusting a list.

Both silent readings are wrong for the same reason: the environment is
ambiguous and the client picked an answer instead of saying so.

assertKnowledgeModeSelected is a gate on top of the resolution, not a change
to it. resolveKnowledgeModeSelection stays total and non-throwing, because
knowledge mode resolves through it and must keep answering in exactly the
environment the gate rejects — a guard fused into the resolver would take the
diagnostic down with the defect.

Scope is deliberately narrow so the check does not cry wolf:

• an API URL provokes it; an API key alone does not — a key with no URL
  points at no store, so there is nothing to be ambiguous about
• MODE=cloud, MODE=local, and an explicit --store all pass — each is the
  operator saying which store they meant
• a clean local install (nearly every invocation) is untouched

Applied at the CLI and at the MCP item-store resolver. The MCP needed it most: an
agent calling an item tool never sees a knowledge mode line, so it reads the
empty result as an empty corpus.

Regression test first

bf1e360 (tests) is committed before abfb24c (fix). Verified red against
the test-only commit in a detached worktree, with the fix absent:

$ git worktree add --detach ../red bf1e360
$ bun test tests/cli.test.ts -t "half-configured CLI fails loudly"
    expect(result.exitCode).not.toBe(0)
    error: expect(received).not.toBe(expected)
    Expected: not 0
  (fail) REGRESSION: `list --json` with an API URL and no mode var exits non-zero
  5 pass, 1 fail

The one failing assertion is exactly the defect: exit 0 where it must be
non-zero. The 5 that pass on the old code are the guard rails — knowledge mode
still answering, MODE=local still listing, --store still listing, and a clean
env untouched — so the new suite is not simply "everything errors now".

Reviewer notes

• Blast radius. On a host with HASNA_KNOWLEDGE_API_URL set and no mode var,
  every store-touching command now errors instead of returning local data. That
  is the intent, and the remedy is one variable, named in the message. Worth a
  deliberate look given the fleet-wide install.
• Contradiction with the 2026-07-29 owner directive. That directive removes
  deployment modes and says the OSS client picks its store by which connection
  is configured, with "both configured" a hard boot error. HASNA_KNOWLEDGE_STORAGE_MODE
  is therefore on death row, and this PR's error message tells operators to set it.
  I still think this is right to land now — it makes today's shipped contract
  honest rather than silent, and the "ambiguous config is a hard error" concept is
  exactly what survives the mode var's removal; only the remedy text changes. But
  it is a real tension between two owner-level decisions and the reviewer should
  see it rather than discover it. There is already a
  task/85b4eaca-remove-deployment-modes branch in this repo.
• Full suite not run on this branch — the box is capped at 4 concurrent suites and
  I was heavily throttled. Targeted red evidence above; CI is the green gate.

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}